---
{
	"title": "Text highlighting",
	"language": "en",
	"category": "Plugins",
	"categoryfile": "plugins",
	"description": "Automatically highlights certain words on a Web page. The highlighted words can be selected via the query string.",
	"altLangPrefix": "texthighlight",
	"dateModified": "2014-08-04"
}
---
<span class="wb-prettify all-pre hide"></span>

<section>
	<h2>Purpose</h2>
	<p>The Text highlighting component highlights any text within a pre-defined area that matches case-insensitive search criteria specified through the URL's query string. Supports multi-word strings, including spaces and basic punctuation.</p>
	<p><strong>Note:</strong> Search criteria using special regex characters such as <code>"</code>, <code>|</code>, <code>?</code>, <code>+</code>, <code>(</code> or <code>)</code> may be partially or fully excluded from the results.</p>
</section>

<section>
	<h2>Use when</h2>
	<ul>
		<li>Highlighting search terms on a search results page</li>
		<li>Highlighting key words on a Web page</li>
		<li>Helping the user to find all instances of one or more words on a Web page</li>
	</ul>
</section>

{{!-- Section for non-text contrast test.
The ratio should be greater than 3:1.
The background color used for highlight is #ffff00 and the font color is #000000, resulting in ratio of 19.55:1.
--}}
<section>
	<h2>Non-text contrast</h2>
	<p>According to <a href="https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html">Understanding Success Criterion 1.4.11: Non-text Contrast</a>, the contrast ratio is required to be at least 3:1.</p>
	<p>The background color used for highlight is #ffff00 and the font color is #000000, resulting in ratio of 19.55:1</p>
</section>

<section>
	<h2>Working example</h2>
	<section>
		<h3>Sample search criteria</h3>
		<ul>
			<li>avian influenza</li>
			<li>world</li>
			<li>cook</li>
			<li>flu-like symptoms</li>
			<li>Don't Forget...</li>
			<li>causes sickness in birds, it can also infect people.</li>
		</ul>

		<p><strong>Query string:</strong> <code>?txthl=avian%20influenza+world+cook+flu-like%20symptoms+Don't%20Forget...+causes%20sickness%20in%20birds,%20it%20can%20also%20infect%20people.</code></p>

		<p><a href="../../../demos/texthighlight/texthighlight-en.html?txthl=avian%20influenza+world+cook+flu-like%20symptoms+Don%27t%20Forget...+causes%20sickness%20in%20birds,%20it%20can%20also%20infect%20people.#example">Highlight example text that meets the search criteria</a></p>
	</section>
</section>

<section>
	<h2>How to implement</h2>
	<ol>
		<li>Define your search area. Add the <code>wb-txthl</code> class to the tag whose contents you want to search in.</li>
		<li>Specify the search criteria in a URL query string. Add <code>txthl=&lt;text_1&gt;+&lt;text_2&gt;+&lt;text_3&gt;</code> to the query string.<br><strong>Note:</strong> HTML markup validation requires all spaces in links to be replaced by <code>%20</code>.</li>
	</ol>
	<p><strong>Note:</strong> HTML markup validation requires all spaces in links to be replaced by <code>%20</code>.</p>
</section>

<section>
	<h2>Configuration options</h2>
	<table class="table">
		<thead>
			<tr>
				<th>Option</th>
				<th>Description</th>
				<th>How to configure</th>
				<th>Values</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td><code>txthl</code></td>
				<td>Query string parameter that specifies the search criteria for the text to highlight.</td>
				<td>Add <code>txthl=&lt;text_1&gt;+&lt;text_2&gt;+&lt;text_3&gt;</code> to the query string.<br><strong>Note:</strong> HTML markup validation requires all spaces in links to be replaced by <code>%20</code>.</td>
				<td>Strings separated by + characters.</td>
			</tr>
		</tbody>
	</table>
</section>

<section>
	<h2>Events</h2>
	<p>Document the public events that can be used by implementers or developers.</p>
	<table class="table">
		<thead>
			<tr>
				<th>Event</th>
				<th>Trigger</th>
				<th>What it does</th>
			</tr>
		</thead>
		<tbody>
			<tr>
				<td><code>wb-init.wb-txthl</code></td>
				<td>Triggered manually (e.g., <code>$( ".wb-txthl" ).trigger( "wb-init.wb-txthl" );</code>).</td>
				<td>Used to manually enhance an element with the Text highlighting plugin. <strong>Note:</strong> The Text highlighting plugin will be initialized automatically unless the element is added after the page has already loaded.</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb-txthl</code> (v4.0.5+)</td>
				<td>Triggered automatically after the Text highlight plugin initializes.</td>
				<td>Used to identify where the Text highlight plugin was initialized (target of the event).
					<pre><code>$( document ).on( "wb-ready.wb-txthl", ".wb-txthl", function( event ) {
});</code></pre>
					<pre><code>$( ".wb-txthl" ).on( "wb-ready.wb-txthl", function( event ) {
});</code></pre>
				</td>
			</tr>
			<tr>
				<td><code>wb-ready.wb</code> (v4.0.5+)</td>
				<td>Triggered automatically when WET has finished loading and executing.</td>
				<td>Used to identify when all WET plugins and polyfills have finished loading and executing.
					<pre><code>$( document ).on( "wb-ready.wb", function( event ) {
});</code></pre>
				</td>
			</tr>
		</tbody>
	</table>
</section>

<section>
	<h2>Source code</h2>
	<p><a href="https://github.com/wet-boew/wet-boew/tree/master/src/plugins/texthighlight">Text highlighting source code on GitHub</a></p>
</section>
